MacWorld 1997 September/Macworld (1997-09).dmg/Shareware World/Utilities/Text Processing/Alpha/Help/MacPerl Help

Text File | 1995-07-31 | 25KB | 619 lines

########################
MacPerl Support in Alpha
########################

Introduction
============

This document describes the use of the MacPerl menu in Alpha.  The
MacPerl menu was written to allow Alpha to act as a front end for
Matthias Neeracher's standalone MacPerl application and to make it
possible to "attach" Perl scripts to Alpha.  It provides a number of
features designed to make the use and development of Perl scripts on the
Mac more convenient.  These are detailed in the rest of this document
(most easily navigated using the "{}" menu on the sidebar), but here's a
quick overview:

Editing Perl scripts...

• Perl keywords and special variables are colorized in Perl mode.

• The Perl 4 man page is provided as an on-line reference,
  available as the file "Perl Commands" in Alpha's Help menu; it has
  been colorized and indexed to make it easy to read and navigate.

• The man page can be referenced by command-double-clicking a
  highlighted Perl keyword or special variable in your Perl script.

• Source files mentioned in require statements can be opened by
  command-double-clicking as well.

Running Perl Scripts...

• MacPerl scripts can be run directly from Alpha - a script can be
  a text window in Alpha, a highlighted selection from a window, or a
  disk file.

• You can save scripts as MacPerl droplets and runtime applications
  directly from Alpha.

• Perl scripts that read from standard input and write to standard
  output may be used to process text in Alpha's text windows.

Debugging Perl scripts...

• When a script fails, the error messages are displayed and the
  script is brought up with the line that caused the error highlighted.

• A flag can be set to cause scripts to run under the Perl
  debugger (without modifying the script).


Currently, no explicit support or documentation is provided for Perl 5,
but this will follow once a stable port of Perl 5 to the 68k Macintosh
emerges.

Instructions for obtaining the MacPerl application are given further below.


Installation
============

No special installation procedure is required before using this package.
However, there are a couple of things that you may need to do to
configure things for your particular machine.

MacPerl application and library
-------------------------------

Alpha needs to know where to find your MacPerl application in order to
interact with it, and will automatically prompt you to locate it if it
doesn't know where it is.  You can always check and/or change the path
that Alpha uses by selecting the "MacPerl" entry in the "Mode:App Paths"
menu.

When opening "require"d source files via the command-double-click
mechanism, Alpha will always look in the "lib" folder in the MacPerl
application directory.  To have Alpha look for library files elsewhere,
you can specify an additional personal library folder, using the
"MacPerl lib folder" entry in "Mode:App Paths" menu.

Text Filters Setup
------------------

If you want to use Perl scripts to process Alpha text buffers (see
Text Filters), you'll need to arrange that the Perl menu is visible
while you're in Text mode.  While in Text mode, select "Set Mode
Menus…" from the "√" pop-up menu on the side-bar and command-click
on "perlMenu" in the list of menus shown.  The little camel icon
should appear on the menu bar when you're done.

The MacPerl menu contains a hierarchical submenu of preattached scripts
to be used as text filters.  A sample collection of such scripts is
distributed with Alpha in the ":Tcl:UserCode:Text Filters:" folder.  You
can specify your own folder of scripts using "MacPerl Text Filters
folder" entry in "Mode:App Paths" menu.

Option flags

There are a handful of flags you can set to modify the way Alpha and
MacPerl interact while running Perl scripts.  These can be set from
either the MacPerl menu or the "√" pop-up menu on the side-bar.  They're
described in detail below.


Perl Mode
=========

Perl mode is entered automatically whenever you open a file with a ".pl"
or ".ph" suffix; you can also invoke it explicitly using the modes menu
(downward triangle) on the sidebar.  Perl mode offers a number of
features supporting the editting and debugging of Perl scripts:

Basic language support
----------------------

• Perl keywords and special variables appear in blue in Perl mode.

• A single line or a selected block of lines may be commented out by
  using the "Comment Line" command under the "Convert" menu.  Lines
  are uncommented using "Uncomment Line", which appears in the "Convert"
  menu when the option key is held down.

• Alpha will create an index of all subroutines in your Perl script when
  you select "Mark File" from the Marks menu on the sidebar (the "{}"
  button).  Once created this index is saved with your file.

  When you open a Perl script that hasn't already been indexed, an index
  is automatically created.

Command-double-clicking
-----------------------

A simple form of hypertext help is invoked by double-clicking on
certain pieces of text while the command key is held down:

• The online man page can be referenced by command-double-clicking a
  highlighted Perl keyword or special variable in your Perl script.

  Most of the clickable keywords and variables will be colored blue.
  Special variables containing alphabetic characters, .e.g. @ARGV,
  are also clickable but are not colored.

• Command-double-clicking on the name of the source file in a require
  statement will cause that file to be opened by Alpha.

  Alpha will look for the file in the current script's folder, in your local
  library folder and in the MacPerl lib folder (in that order).  The local
  lib folder may be specified interactively by the user (see Installation).



MacPerl Menu
============

Alpha's MacPerl menu allows a number of actions.  These are ...

MacPerl interaction
-------------------

Macperl                  Switch to the MacPerl application.

Tell Macperl... >

    Open In Macperl        Open the current document in MacPerl.

    Save As Droplet        Save the current document as a MacPerl droplet.

    Save As Droplet        Save the current document as a MacPerl runtime script.

    Save As CGI            Save the current document as a MacPerl CGI applet.

                A bug in the AEGizmos package makes it impossible to create
                CGI applets directly from Alpha at this point.  You will have
                to open the script in MacPerl and save it from there.

    Open Output Window     Retrieve the contents of MacPerl's main output window
                        into a new window under Alpha.

    Close Output Window    Close MacPerl's main output and debugger windows.

    Quit                  Force the MacPerl application to quit.

Running Perl Scripts
--------------------

Run The Selection      Execute the selected text as a Perl script.

Run The Buffer      Execute the current text window as a Perl script.

Save And Run          Save the current window and run the saved file as
                    a Perl script. (see Current Directory)

Run A File          Run a selected disk file as a Perl script.

Applying Text Filter Scripts
----------------------------

Text Filters >    A hierarchical menu of "preattached" scripts to use
                as text filters.  When a script is selected from this menu,
                it is immediately applied to the current text window.

                The menu is built from the contents of a user-selected
                folder.  The folder is chosen using the "Mode:App Paths"
                menu command on the main menubar or the "Text Filters Folder"
                command under the Macperl "Filter Options" submenu (below).

Select Buffer As Filter    Select one of the open text windows to use as the
                        text filter script.

Select File As Filter    Select a file to use as the text filter script.

Repeat Last Filter        Run again the last filter that was used.

                        If the contents of the file or buffer has changed, the
                        new script is run.


Option flags
------------

General Options >    Flags that control Alpha's behavior when executing
                    ordinary scripts (not text filters).

     Retrieve Output        Automatically retrieve any output written to the
                         MacPerl output window and display it in a new
                         window under Alpha. (same as "perlGetOutput")

                         If the mode variable "perlRecycleOutput" is set,
                         the previous output window is overwritten.

     Auto Switch            Switch to MacPerl while scripts are being executed.
                         Otherwise, Alpha remains frontmost until the script
                         finishes. (same as "perlAutoSwitch")

     Prompt For Args        Have Alpha prompt you for command-line arguments
                         to be passed to the script. (same as "perlPromptArgs")

    Use Debugger         Force the script to run under the MacPerl debugger.
                        (same as "perlUseDebug")

                         Control is automatically switched to MacPerl
                         when the debugger is used.

Filter Options >        Flags controlling the behavior of text filters mechanism.

     Apply To Buffer        Apply the filter to the entire current text window;
                         otherwise, only the selected text is used.
                        (same as "perlUseBuffer")

     Overwrite Selection    When checked, the output from the text filter
                         script will replace the input text in the original
                         window.  Otherwise, the output is written into
                         a new window.
                        (same as "perlOverwrite")

    Text Filters Folder  Select the folder from which the Text Filters menu is
                        built.  (You can also use the "Mode:App Paths" menu.)

    Rebuild Filter Menu  Reconstruct the "Text Filters" menu from the
                        contents of the designated "Text Filters" folder.


Mode variables
--------------

A more complete set of Perl option flags are also settable through the
flags menu "√" on the sidebar (while you're in Perl mode).

perlAutoSwitch         (same as "Auto Switch" under "General Options")
perlGetOutput        (same as "Retrieve Output" under "General Options")
perlOverwrite        (same as "Overwrite Selection" under "Filter Options")
perlPromptArgs         (same as "Prompt For Args" under "General Options")
perlUseDebug         (same as "Use Debugger" under "General Options" )
perlUsebuffer         (same as "Apply To Buffer" under "Filter Options")

perlRecycleOutput     If selected, output returned by Macperl overwrites
                    previous output in the "* Perl Output *" window in Alpha,
                    instead of going into a new window.

There are also two mode variables that may be examined

perlLastFilter        Contains the location of the last text-filter script used.

perlCmdlineArgs     Contains the last command-line options supplied.

                    Note these are only passed to scripts when the "Prompt for
                    Args" option is active.


Running Scripts
===============

Running scripts using the MacPerl menu is pretty straightforward.  You
can send the current selection, the entire current buffer, or a disk
file to MacPerl for execution as a Perl script; the result will be the
same as if you ran the script from MacPerl itself.  Here are listed some
important points to remember when running Perl scripts using the MacPerl
menu.

Input and Output
----------------

•    Except for text filter scripts, the standard input for your script
    is taken from the keyboard (while MacPerl is in the foreground)
    and standard output goes to MacPerl's output window.

    If you need to interact with the script while it's running, make
    sure that you've selected the "AutoSwitch" flag under "General
    Options".

•    To get the output from your script, select the "Retrieve Output"
    flag under "General Options", this will cause Alpha to copy any
    output to Macperl's standard output window back into Alpha after
    your script has completed.  You can always do this manually by
    using the "Get Output Window" command under the "Tell Macperl…"
    submenu.

    Again, if you need to see the results while the script is running,
    use "AutoSwitch" to bring MacPerl to the foreground during script
    execution.

Current Directory
-----------------

For the purpose of resolving relative file references, etc., within your
script, it's important to understand how the current directory of the
running script (as returned by `pwd` ) is determined.

•    If you run a script file (using "Run A File"), then the folder
    containing that file is the current folder.

•    If you run a script from a text buffer (using "Run The Buffer" or "Run
    The Selection") , it is as though you ran it directly from a window in
    the MacPerl application, and so the current directory your script sees
    is the MacPerl application folder.

•    If you run a script from a buffer using the "Save and Run" command,
    then the script is first saved to disk and then executed as a script
    file.  In this case, the current directory is that of the script file.


Command-line Args
-----------------

• If the menu flag "Prompt For Args" is checked, then the user is prompted
  for command-line arguments at the time the script is run.  These will be
  available inside the script through the @ARGV array, as usual.  They are
  also saved in the Perl-mode variable "perlCmdlineArgs", and become the
  default arguments the next time the script is executed.

Error Messages
--------------

• If the script fails for some reason, Alpha will read the error messages
  returned by MacPerl and write them back into a new text window, called
  "* Perl Errors *".

• The script that generated the error is brought up
  and the first line specifically referenced in an error message is
  highlighted.

  Note that error-trapping remains active whether "Retrieve Output" is set
  or not.

Interrupting a Script
---------------------

When you run a Perl script from Alpha, Alpha will display the watch
cursor and wait for the reply from Macperl before doing anything else.
There may be times when this is inappropriate, for instance, if you
expect the script to run for a long time or if you think the script is
misbehaving for some reason.

• You can always tell Alpha to stop waiting for a script to finish by
  hitting "Cmd-.".

  This does not abort the script itself; to do that you'll have to switch
  over to MacPerl to terminate the script there, as well.

• When you interrupt a script in this way, Alpha will no longer
  automatically get the output or error messages from MacPerl, when and if
  the script does finally terminate.

  You can always retrieve the contents of the output window yourself using
  "Get Output Window" from the "Tell MacPerl…" submenu or simply by
  switching over to Macperl itself.

There are some simple causes for a hung script.  For instance, if
MacPerl is configured to check for "#!" lines in scripts and yours
doesn't have one, it will put up a dialog asking whether or not to
procede.  If you didn't switch over to MacPerl when the script was run,
you have know way of knowing this, and so you and Alpha may end up just
sitting there waiting.


Text Filters
============

Perl is, among other things, a powerful tool for extracting and
rewriting data from text files.  On a Unix system, one would
typically write text-processing scripts to read from "standard
input" and write to "standard output", taking advantage of
command-line i/o redirection to specify the actual input and output
files used at any given time.  On the Mac, the typical absence of a
command-line interface makes it harder to use this elegant method.

The MacPerl menu in Alpha makes it possible to use scripts that
read from standard input and write to standard output to process
text buffers in Alpha directly.  Any text window can be used as
standard input and standard output can either be directed back to
that same window or to a newly created one.  The script used may
either be a disk file or yet another Alpha text window.

Applying a Text Filter
----------------------

The procedure for using Perl text filters in Alpha is simple:

1.  Bring the text window you want to operate on to the front and select
    (highlight) the text that will be the input to the script.

   * If the "Apply To Buffer" option is selected, then the entire text
     window will be used as input and any text selection is ignored.

   * Only complete lines are used as input.  The text used will be extended
     to include all of the lines on which the selected text lies.

2.    Select a Perl script using one of the commands, "Select Buffer As
    Filter", "Select File As Filter" or "Repeat Last Filter" from the Perl
    menu, or by choosing one of the scripts listed in the "Text Filters"
    submenu.

   * You can see the name of the last script used by examining the
     variable "perlLastFilter" under the "√" menu in Perl mode. This
     is the script that will be used if you use "Repeat Last Filter"

   * If the "Prompt For Args" option has been selected, you'll be given
     a dialog box to type in the command-line arguments for the script.

3.  The output of the script is written back out, either in the place of
    the input text (if the "Overwrite Selection" option is selected) or into
    a new text window.

    * As always, Alpha's unlimited undo capability let's you recover if you
      accidently overwrite the input text when you didn't want to.

    * If the script halts on an error, the filter operation is aborted
      and any error messages are displayed in a new window.


The ability to take the script itself from a text window allows simple
one-time scripts to be created and applied on the fly.  This can be very
useful because, even with the overhead to start up MacPerl, large-scale
global search-and-replace operations (hundreds of replaces) can be
substantially faster in MacPerl than in Alpha.  Also, you might find
it easier to apply a series of regular expression substitutions using a
single, short Perl script, rather than a number of separate "Find" and
"Replace All" commands in Alpha.


Preattached Scripts
-------------------

Frequently used text filter scripts can be conveniently accessed by
placing them in a folder called "Text Filters" within the MacPerl
application folder.  When the MacPerl menu is first created, it looks in
this folder and builds a hierarchical submenu from the names of the
scripts that it finds.  Note that it will also create a "Text Filters"
folder if one doesn't already exist.

A sampling of useful :-) Perl scripts is distributed with Alpha in
the folder ":Tcl:UserCode:Text Filters".

Of the scripts in the sample collection, the "Text Munging" scripts
("shuffle", "sort lines", "travesty", and "wordcount") were taken from
the Camel book (Programming Perl).  The "s2p" script is my adaptation
of the standard code that converts Unix "sed" scripts to Perl (it was
modified to work without using the C preprocessor.) "Strip Mail Headers"
takes e-mail files and edits out any header lines but the few that I
typically care about ("From:, "Date:", etc..).  "CC To BibTeX" is a
script I use that takes listings from the online "Current Contents"
database and rewrites them as BibTeX database entries.  To try it out,
select (highlight) the sample Current Contents citation below and choose
"CC To BibTeX" from the "Text Filters" submenu (make sure that "Apply
To Buffer" is _not_ checked before you do!)

288. VOS MH; LAMBRY JC; ROBLES SJ; YOUVAN DC; and others.
       FEMTOSECOND SPECTRAL EVOLUTION OF THE EXCITED STATE OF BACTERIAL
     REACTION CENTERS AT 10-K.
       PROCEEDINGS OF THE NATIONAL ACADEMY OF SCIENCES OF THE UNITED STATES OF
     AMERICA, 1992 JAN 15, V89 N2:613-617.


Bugs, etc.
==========

Comments and suggestions regarding this package are always welcome.  If
there's something that bothers you, or some additional capability that
you'd like to see, let me know and I'll see what I can do.

Bug reports and any other comments should be directed to

     Tom Pollard <[e-mail]>


Version History
===============

2.3  7/95  -  Minor tweaks and code rearrangement.
2.2  6/95  -  Text filters act only on current line if "Apply to Buffer" is
                 false and no text has been selected.
              More verbose commentary when running scripts.
              Bug fix in error-marking for scripts sent as AppleEvent parameters.
              Cmd-dbl-clicking a function call jumps to function, if
                 defined in the same file.
2.1  6/95  -  Cmd-dbl-clicking a 'require'd filename opens the file.
2.0  6/95  -  Minor bug fixes (incl. keyword decapitalization), and
              Alpha 6.0b17 compatibility updates.
              Text Filters folder is settable from the App Paths menu now.
1.9  5/95  -  Cmd-dbl-clicking Perl keywords and special variables displays
                 the man page info.
1.8  4/95  -  Menu reorganized somewhat.
              Text Filters folder can now be anywhere.
              "ApplyToBuffer" flag ignored if text has been selected.
1.7  1/95  -  Updated to take advantage of MacPerl 4.1.4 AppleEvent features:
               1) Text filters use 'batch' doScript (.: STDOUT file obsolete)
               2) Filter scripts sent as doScript params (.: SCRIPT file obsolete)
               3) "Save As Droplet" and "Save as Runtime" commands added.
              Errors generated in 'require'd files are now displayed correctly
1.6 10/94  -  "UseDebugger" flag added (forces scripts to run under debugger).
              Key bindings added for some menu commands.
              "perlDoScript{,2,3}" procs consolidated into a single proc.
              "saveAndRun" option added.
              Command-line args now parsed into units more correctly, in
                  particular, quoted file names aren't broken up.
              "Close Output Window" added to "Tell MacPerl" menu.
              Updated for Alpha 5.98 to load when menu is inserted.
              The error messages window is now recycled.
              "perlRecycleOutput" recycles output window.
              Minor bug fixes.
1.5  9/94  -  MacPerl menu rearranged somewhat.
              Explicit "Get Output Window" command added to menu.
              Reading "#!" line for args is incompatible w/ standard,
                  so it's been dropped.
              Only scan the first 40 output lines for error messages (faster)
              "wrapFilterScript" no longer opens STDIN
              Text filters may now use command-line args
              STDIN for text filters passed as explicit cmd-line arg
1.4  9/94  -  The "#!" line of every script is read for command-line args.
              "PromptForArgs" menu flag added.
              "perlCmdlineArgs" modeVar holds default command-line args.
              Scripts are sent using custom "perlDoScript2" proc.
1.3  9/94  -  When any script generates a compilation error, the file
                  containing the script is brought up with the offending
                  line highlighted; all error output is also written to
                  a "Perl Error Messages" window.
              'repeatLastFilter' runs again the last text-filter script used.
              'perlLastFilter' modeVar holds pathname of last filter.
              Menu flags now mirrored as modeVars, so they can be saved and
                  restored between sessions.
              Minor bug fixes.
1.2  8/94  -  'retrieveOutput' and 'autoSwitch' flags added.
              'openInMacperl' added.
              MacPerl output window now closed before new scripts are sent.
              Filters now abort if there are compilation errors, and
                   MacPerl diagnostic output retrieved and displayed.
1.1  8/94  -  'quitMacperl' added.
              perl-mode file-marking updated for Alpha 5.90
              Simplified installation via 'loadMacperl'(Pete Keleher).
1.0  7/94  -  perl-mode setup updated for Alpha 5.85:
                   keyword colorization supported
                   custom file-marking added
              #! lines in filter scripts now handled correctly
              Workarounds installed for AppleEvent problem in MacPerl 4.1.3
0.9  3/94  -  perl-mode stuff added, and
              highlighted 'Perl commands' file (man page) prepared
              minor bug fixes, too
0.8  3/94  -  flags are now check-marked
0.7  3/94  -  nested Text Filters folder now supported
              menu format modified somewhat
0.6  3/94  -  'applyToBuffer' flag added
              scripts in Alpha buffers can now be used as filters
0.5  2/94  -  'filters', 'open special' submenu added
              'overwrite' flag added
0.2  1/94  -  menu support added by Martijn Koster <[e-mail]>
              'execute selection', 'execute buffer' commands added
0.1  9/93  -  text filter functionality created


MacPerl application
===================

MacPerl was written (ported to the Mac) by

          Matthias Neeracher <[e-mail]>, and
          Tim Endres <[e-mail]>.

If you don't already have MacPerl, it's available by anonymous ftp

  ftp://ftp.switch.ch/software/mac/perl ,  or
  ftp://ftp.share.com/pub/macperl


More information about MacPerl is available from the MacPerl Q&A page,

  http://err.ethz.ch/members/neeri/macintosh/perl-qa.html ,

Hal Wine's official MacPerl FAQ,

  ftp://ftp.netcom.com/pub/ha/hal/MacPerl/

and Sandra Silcott's MacPerl Primer,

  http://www.unimelb.edu.au/~ssilcot/macperl-primer/home.html

which contains useful hints and sample scripts.

---------------------------------------------------------------------------